media_player add off on capability #1092
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
for more information, see https://pre-commit.ci
## Walkthrough
The changes update the protocol buffer definitions and Python model for media player functionality by adding three new states and nine new commands to the `MediaPlayerState` and `MediaPlayerCommand` enums. The `ListEntitiesMediaPlayerResponse` message adds a new `feature_flags` field. The Python `MediaPlayerInfo` dataclass gains a `feature_flags` attribute and a compatibility method for API versions. Tests were added to verify feature flag compatibility.
## Changes
| Cohort / File(s) | Change Summary |
|--------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| **Protocol Buffers**<br>`aioesphomeapi/api.proto` | Extended `MediaPlayerState` and `MediaPlayerCommand` enums with new values; added `feature_flags` field to `ListEntitiesMediaPlayerResponse`. |
| **Model Definitions**<br>`aioesphomeapi/model.py` | Added `MediaPlayerEntityFeature` IntFlag enum; extended `MediaPlayerState` and `MediaPlayerCommand` enums; added `feature_flags` attribute and `feature_flags_compat` method to `MediaPlayerInfo`. |
| **Tests**<br>`tests/test_model.py` | Updated test to include `feature_flags` in media player info; added test for `feature_flags_compat` method verifying compatibility across API versions. |
## Sequence Diagram(s)
```mermaid
sequenceDiagram
participant Client
participant API
participant MediaPlayer
Client->>API: ListEntitiesMediaPlayer
API->>MediaPlayer: Query media player capabilities and state
MediaPlayer-->>API: States, commands, feature_flags
API-->>Client: ListEntitiesMediaPlayerResponse (with updated states, commands, feature_flags)Estimated code review effort🎯 3 (Moderate) | ⏱️ ~15 minutes |
CodSpeed Performance ReportMerging #1092 will not alter performanceComparing Summary
Footnotes |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1092 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 20 20
Lines 3028 3032 +4
=========================================
+ Hits 3028 3032 +4 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
aioesphomeapi/api.proto(4 hunks)aioesphomeapi/client.py(2 hunks)aioesphomeapi/model.py(4 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
`**`: - Do not generate or add any sequence diagrams
**: - Do not generate or add any sequence diagrams
aioesphomeapi/client.pyaioesphomeapi/api.protoaioesphomeapi/model.py
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: py 3.12 on windows-latest (skip_cython)
🔇 Additional comments (8)
aioesphomeapi/client.py (1)
1232-1260: New media player command parameters look good.The additions of
enqueueandgroup_membersparameters to themedia_player_commandmethod are well-implemented, with proper optional typing and conditional flag setting. The implementation follows the same pattern as the existing parameters.aioesphomeapi/api.proto (4)
1127-1159: Media player state and command enums expanded appropriately.The new states and commands enhance the media player functionality as described in the PR objectives, adding support for announcements, power control, track navigation and playback controls.
1190-1193: Support flags for new media player capabilities.The new boolean capability flags correctly implement the planned functionality additions: turning media players on/off, grouping players together, and navigating between tracks.
1203-1210: Enhanced media player state attributes.The additional fields for song metadata and playback state provide much more detailed information about currently playing media, which will greatly improve the user experience.
1231-1236: Command request fields for new functionality.The enqueue and group_members fields enable the new features and follow the same pattern as existing command parameters with appropriate has_* flags.
aioesphomeapi/model.py (3)
813-816: Media player state enum values correctly added.The new state enum values match the protocol definitions and enable the new functionality.
872-875: Media player info capability flags properly added.These flags correctly correspond to the new fields in the ListEntitiesMediaPlayerResponse message.
891-899: Media player state information significantly enhanced.The new attributes in MediaPlayerEntityState provide rich metadata about media playback, matching the protocol definition.
…lle/aioesphomeapi into media_player_all_features
for more information, see https://pre-commit.ci
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
aioesphomeapi/model.py (2)
873-875: Consider renaming for clarity.
supports_turn_off_onmight be more consistent if namedsupports_turn_on_offorsupports_power_toggleto match reading order and be more descriptive. This is a minor naming nitpick but can improve clarity.
891-899: Consider using strong types for repeat/shuffle/timing fields.Storing
repeatas a string andduration/positionas integers can work, but using dedicated enums (for repeat/shuffle) or floats (for more precise timing) can improve type safety and clarity. Otherwise, please ensure robust validation for string-basedrepeatvalues.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
aioesphomeapi/model.py(4 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
`**`: - Do not generate or add any sequence diagrams
**: - Do not generate or add any sequence diagrams
aioesphomeapi/model.py
🔇 Additional comments (2)
aioesphomeapi/model.py (2)
814-816: Check for feature usage of newly introduced states.These new states (
OFF,ON, andANNOUNCING) appear valid. Please ensure they are handled throughout the codebase wherever a media player state might be set or interpreted, so that existing code that expects onlyIDLE,PLAYING, orPAUSEDdoes not encounter unexpected behavior.
825-840: All new commands are well-structured and consistent.Thank you for fixing the previous tuple-related syntax. These commands integrate well with the existing
MediaPlayerCommandpattern.
bdraco
added
the
waiting-for-esphome
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
aioesphomeapi/client.py (1)
1231-1262: Consider adding documentation for the new parametersThe method lacks docstring documentation explaining what the new parameters do. Adding documentation would improve developer experience and code maintenance.
def media_player_command( self, key: int, *, command: MediaPlayerCommand | None = None, volume: float | None = None, media_url: str | None = None, announcement: bool | None = None, enqueue: str | None = None, group_members: str | None = None, ) -> None: + """Send a command to a media player. + + Args: + key: The key identifying the media player. + command: The command to send to the media player. + volume: The volume to set on the media player. + media_url: The URL of media to play. + announcement: Whether this is an announcement. + enqueue: The enqueue option for the media player. + group_members: The group members for the media player when operating in group mode. + """ req = MediaPlayerCommandRequest(key=key)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
aioesphomeapi/client.py(2 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
`**`: - Do not generate or add any sequence diagrams
**: - Do not generate or add any sequence diagrams
aioesphomeapi/client.py
🔇 Additional comments (2)
aioesphomeapi/client.py (2)
1239-1240: Method signature enhancement for extended media player functionalityThe addition of
enqueueandgroup_membersparameters aligns well with the PR objectives, enabling support for the media player enqueueing functionality and grouping capabilities.
1255-1260: Implementation follows consistent parameter handling patternThe implementation for the new parameters follows the established pattern in the codebase, properly checking for
Nonevalues before setting the request attributes and their corresponding flags.
|
close/reopen to restart CI to fix codspeed settings |
rwrozelle
changed the title
|
Is there a PR on the main ESPhome repo to accompany this PR? If so please link it in the opening text as we need that one to be approved before this can merge |
|
I have the code, but have not sent in a PR for it, I will work on that. |
bdraco
reviewed
Jul 28, 2025
bdraco
reviewed
Jul 28, 2025
bdraco
reviewed
Jul 28, 2025
bdraco
reviewed
Jul 28, 2025
bdraco
reviewed
Jul 28, 2025
bdraco
reviewed
Jul 28, 2025
bdraco
reviewed
Jul 28, 2025
bdraco
reviewed
Jul 28, 2025
bdraco
reviewed
Jul 28, 2025
bdraco
reviewed
Jul 28, 2025
bdraco
reviewed
Jul 28, 2025
bdraco
reviewed
Jul 28, 2025
bdraco
reviewed
Jul 28, 2025
bdraco
reviewed
Jul 28, 2025
bdraco
approved these changes
Jul 28, 2025
|
@rwrozelle please resolve conflicts. Thanks |
|
MediaPlayerInfo.feature_flags_compat will not return the value from feature_flags set by esphome until API 1.11 is released. |
bdraco
approved these changes
Jul 30, 2025
bdraco
removed
the
waiting-for-esphome
|
Probably should have bumped the minor version but not a big deal |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
ESPHome PR esphome/esphome#9294
Extends the media_player to additional features. supports_turn_off_on
Dependent on PR: #1285